GFM

A link reference definition (opens new window) consists of a link label (opens new window), indented up to three spaces, followed by a colon (:), optional whitespace (opens new window) (including up to one line ending (opens new window)), a link destination (opens new window), optional whitespace (opens new window) (including up to one line ending (opens new window)), and an optional link title (opens new window), which if it is present must be separated from the link destination (opens new window)by whitespace (opens new window). No further non-whitespace characters (opens new window) may occur on the line.

A link reference definition (opens new window) does not correspond to a structural element of a document. Instead, it defines a label which can be used in reference links (opens new window) and reference-style images (opens new window) elsewhere in the document. Link reference definitions (opens new window) can come either before or after the links that use them.

Example 161

Markdown HTML Demo
 
[foo]: /url "title"

[foo]


<p><a href="/url" title="title">foo</a></p>

Example 162

Markdown HTML Demo
 
   [foo]: 
      /url  
           'the title'  

[foo]


<p><a href="/url" title="the title">foo</a></p>

Example 163

Markdown HTML Demo
 
[Foo*bar\]]:my_(url) 'title (with parens)'

[Foo*bar\]]


<p><a href="my_(url)" title="title (with parens)">Foo*bar]</a></p>

Example 164

Markdown HTML Demo
 
[Foo bar]:
<my url>
'title'

[Foo bar]


<p><a href="my%20url" title="title">Foo bar</a></p>

The title may extend over multiple lines:

Example 165

Markdown HTML Demo
 
[foo]: /url '
title
line1
line2
'

[foo]


<p><a href="/url" title="
title
line1
line2
">foo</a></p>

However, it may not contain a blank line (opens new window):

Example 166

Markdown HTML Demo
 
[foo]: /url 'title

with blank line'

[foo]


<p>[foo]: /url 'title</p>
<p>with blank line'</p>
<p>[foo]</p>

The title may be omitted:

Example 167

Markdown HTML Demo
 
[foo]:
/url

[foo]


<p><a href="/url">foo</a></p>

The link destination may not be omitted:

Example 168

Markdown HTML Demo
 
[foo]:

[foo]


<p>[foo]:</p>
<p>[foo]</p>

However, an empty link destination may be specified using angle brackets:

Example 169

Markdown HTML Demo
 
[foo]: <>

[foo]


<p><a href="">foo</a></p>

The title must be separated from the link destination by whitespace:

Example 170

Markdown HTML Demo
 
[foo]: <bar>(baz)

[foo]


<p>[foo]: <bar>(baz)</p>
<p>[foo]</p>

Both title and destination can contain backslash escapes and literal backslashes:

Example 171

Markdown HTML Demo
 
[foo]: /url\bar\*baz "foo\"bar\baz"

[foo]


<p><a href="/url%5Cbar*baz" title="foo&quot;bar\baz">foo</a></p>

A link can come before its corresponding definition:

Example 172

Markdown HTML Demo
 
[foo]

[foo]: url


<p><a href="url">foo</a></p>

If there are several matching definitions, the first one takes precedence:

Example 173

Markdown HTML Demo
 
[foo]

[foo]: first
[foo]: second


<p><a href="first">foo</a></p>

As noted in the section on Links (opens new window), matching of labels is case-insensitive (see matches (opens new window)).

Example 174

Markdown HTML Demo
 
[FOO]: /url

[Foo]


<p><a href="/url">Foo</a></p>

Example 175

Markdown HTML Demo
 
[ΑΓΩ]: /φου

[αγω]


<p><a href="/%CF%86%CE%BF%CF%85">αγω</a></p>

Here is a link reference definition with no corresponding link. It contributes nothing to the document.

Example 176

Markdown HTML Demo
 
[foo]: /url

Here is another one:

Example 177

Markdown HTML Demo
 
[
foo
]: /url
bar


<p>bar</p>

This is not a link reference definition, because there are non-whitespace characters (opens new window) after the title:

Example 178

Markdown HTML Demo
 
[foo]: /url "title" ok


<p>[foo]: /url &quot;title&quot; ok</p>

This is a link reference definition, but it has no title:

Example 179

Markdown HTML Demo
 
[foo]: /url
"title" ok


<p>&quot;title&quot; ok</p>

This is not a link reference definition, because it is indented four spaces:

Example 180

Markdown HTML Demo
 
    [foo]: /url "title"

[foo]


<pre><code>[foo]: /url &quot;title&quot;
</code></pre>
<p>[foo]</p>

This is not a link reference definition, because it occurs inside a code block:

Example 181

Markdown HTML Demo
 
```
[foo]: /url
```

[foo]


<pre><code>[foo]: /url
</code></pre>
<p>[foo]</p>

A link reference definition (opens new window) cannot interrupt a paragraph.

Example 182

Markdown HTML Demo
 
Foo
[bar]: /baz

[bar]


<p>Foo
[bar]: /baz</p>
<p>[bar]</p>

However, it can directly follow other block elements, such as headings and thematic breaks, and it need not be followed by a blank line.

Example 183

Markdown HTML Demo
 
# [Foo]
[foo]: /url
> bar


<h1><a href="/url">Foo</a></h1>
<blockquote>
<p>bar</p>
</blockquote>

Example 184

Markdown HTML Demo
 
[foo]: /url
bar
===
[foo]


<h1>bar</h1>
<p><a href="/url">foo</a></p>

Example 185

Markdown HTML Demo
 
[foo]: /url
===
[foo]


<p>===
<a href="/url">foo</a></p>

Several link reference definitions (opens new window) can occur one after another, without intervening blank lines.

Example 186

Markdown HTML Demo
 
[foo]: /foo-url "foo"
[bar]: /bar-url
  "bar"
[baz]: /baz-url

[foo],
[bar],
[baz]


<p><a href="/foo-url" title="foo">foo</a>,
<a href="/bar-url" title="bar">bar</a>,
<a href="/baz-url">baz</a></p>

Link reference definitions (opens new window) can occur inside block containers, like lists and block quotations. They affect the entire document, not just the container in which they are defined:

Example 187

Markdown HTML Demo
 
[foo]

> [foo]: /url


<p><a href="/url">foo</a></p>
<blockquote>
</blockquote>

Whether something is a [link reference definition] is independent of whether the link reference it defines is used in the document. Thus, for example, the following document contains just a link reference definition, and no visible content:

Example 188

Markdown HTML Demo
 
[foo]: /url